home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 May: Tool Chest / Dev.CD May 98 TC.toast / Tool Chest / Development Kits / • Other Platforms / PCCTS 1.31 / Documentation / antlr.1 < prev    next >
Encoding:
Text File  |  1995-03-10  |  10.9 KB  |  226 lines  |  [TEXT/MPS ]
  1. .TH ANTLR 1 "April 1994" "ANTLR" "PCCTS Manual Pages"
  2. .SH NAME
  3. antlr \- ANother Tool for Language Recognition
  4. .SH SYNTAX
  5. .LP
  6. \fBantlr\fR [\fIoptions\fR] \fIgrammar_files\fR
  7. .SH DESCRIPTION
  8. .PP
  9. \fIAntlr\fP converts an extended form of context-free grammar into a
  10. set of C functions which directly implement an efficient form of
  11. deterministic recursive-descent LL(k) parser.  Context-free grammars
  12. may be augmented with predicates to allow semantics to influence
  13. parsing; this allows a form of context-sensitive parsing.  Selective
  14. backtracking is also available to handle non-LL(k) and even
  15. non-LALR(k) constructs.  \fIAntlr\fP also produces a definition of a
  16. lexer which can be automatically converted into C code for a DFA-based
  17. lexer by \fIdlg\fR.  Hence, \fIantlr\fR serves a function much like
  18. that of \fIyacc\fR, however, it is notably more flexible and is more
  19. integrated with a lexer generator (\fIantlr\fR directly generates
  20. \fIdlg\fR code, whereas \fIyacc\fR and \fIlex\fR are given independent
  21. descriptions).  Unlike \fIyacc\fR which accepts LALR(1) grammars,
  22. \fIantlr\fR accepts LL(k) grammars in an extended BNF notation \(em
  23. which eliminates the need for precedence rules.
  24. .PP
  25. Like \fIyacc\fR grammars, \fIantlr\fR grammars can use
  26. automatically-maintained symbol attribute values referenced as dollar
  27. variables.  Further, because \fIantlr\fR generates top-down parsers,
  28. arbitrary values may be inherited from parent rules (passed like
  29. function parameters).  \fIAntlr\fP also has a mechanism for creating
  30. and manipulating abstract-syntax-trees.
  31. .PP
  32. There are various other niceties in \fIantlr\fR, including the ability to
  33. spread one grammar over multiple files or even multiple grammars in a single
  34. file, the ability to generate a version of the grammar with actions stripped
  35. out (for documentation purposes), and lots more.
  36. .SH OPTIONS
  37. .IP "\fB-ck \fIn\fR"
  38. Use up to \fIn\fR symbols of lookahead when using compressed (linear
  39. approximation) lookahead.  This type of lookahead is very cheap to
  40. compute and is attempted before full LL(k) lookahead, which is of
  41. exponential complexity in the worst case.  In general, the compressed
  42. lookahead can be much deeper (e.g, \f(CW-ck 10\fP) than the full
  43. lookahead (which usually must be less than 4).
  44. .IP \fB-CC\fP
  45. Generate C++ output from both ANTLR and DLG.
  46. .IP \fB-cr\fP
  47. Generate a cross-reference for all rules.  For each rule, print a list
  48. of all other rules that reference it.
  49. .IP \fB-ct\fP
  50. Do not make copies of tokens passed to the parser in C++ mode
  51. (default=to copy).  When using DLG in conjunction with ANTLR, you will
  52. always want ANTLR to make copies because DLG only has space for one
  53. \f(CWANTLRToken\fP (which is passed to the scanner with
  54. \f(CWsetToken\fP); this address is always returned and, hence, without
  55. copies, all $-variables would point to the same \f(CWANTLRToken\fP.
  56. .IP \fB-e1\fP
  57. Ambiguities/errors shown in low detail (default).
  58. .IP \fB-e2\fP
  59. Ambiguities/errors shown in more detail.
  60. .IP \fB-e3\fP
  61. Ambiguities/errors shown in excruciating detail.
  62. .IP "\fB-fe\fP file"
  63. Rename \fBerr.c\fP to file.
  64. .IP "\fB-fh\fP file"
  65. Rename \fBstdpccts.h\fP header (turns on \fB-gh\fP) to file.
  66. .IP "\fB-fl\fP file"
  67. Rename lexical output, \fBparser.dlg\fP, to file.
  68. .IP "\fB-fm\fP file"
  69. Rename file with lexical mode definitions, \fBmode.h\fP, to file.
  70. .IP "\fB-fr\fP file"
  71. Rename file which remaps globally visible symbols, \fBremap.h\fP, to file.
  72. .IP "\fB-ft\fP file"
  73. Rename \fBtokens.h\fP to file.
  74. .IP \fB-ga\fP
  75. Generate ANSI-compatible code (default case).  This has not been
  76. rigorously tested to be ANSI XJ11 C compliant, but it is close.  The
  77. normal output of \fIantlr\fP is currently compilable under both K&R,
  78. ANSI C, and C++\(emthis option does nothing because \fIantlr\fP
  79. generates a bunch of #ifdef's to do the right thing depending on the
  80. language.
  81. .IP \fB-gc\fP
  82. Indicates that \fIantlr\fP should generate no C code, i.e., only
  83. perform analysis on the grammar.
  84. .IP \fB-gd\fP
  85. C code is inserted in each of the \fIantlr\fR generated parsing functions to
  86. provide for user-defined handling of a detailed parse trace.  The inserted
  87. code consists of calls to the user-supplied macros or functions called
  88. \fBzzTRACEIN\fR and \fBzzTRACEOUT\fP.  The only argument is a
  89. \fIchar *\fR pointing to a C-style string which is the grammar rule
  90. recognized by the current parsing function.  If no definition is given
  91. for the trace functions, upon rule entry and exit, a message will be
  92. printed indicating that a particular rule as been entered or exited.
  93. .IP \fB-ge\fP
  94. Generate an error class for each non-terminal.
  95. .IP \fB-gh\fP
  96. Generate \fBstdpccts.h\fP for non-ANTLR-generated files to include.
  97. This file contains all defines needed to describe the type of parser
  98. generated by \fIantlr\fP (e.g. how much lookahead is used and whether
  99. or not trees are constructed) and contains the \fBheader\fP action
  100. specified by the user.
  101. .IP \fB-gk\fP
  102. Generate parsers that delay lookahead fetches until needed.  Without
  103. this option, \fIantlr\fP generates parsers which always have \fIk\fP
  104. tokens of lookahead available.  This option is incompatible with
  105. \fB-pr\fP and renders references to \fBLA(\fIi\fB)\fR invalid as
  106. one never knows when the \fIith\fP token of lookahead will be fetched.
  107. .IP \fB-gl\fP
  108. Generate line info about grammar actions in C parser of the form
  109. \fB#\ \fIline\fP\ "\fIfile\fP"\fR which makes error messages from
  110. the C/C++ compiler make more sense as they will \*Qpoint\*U into the
  111. grammar file not the resulting C file.  Debugging is easier as well,
  112. because you will step through the grammar not C file.
  113. .IP "\fB-gp \fIprefix\fR"
  114. Prefix all functions generated from rules with \fIprefix\fP.  This is now
  115. obsolete.  Use the \*Q#parser "name"\*U \fIantlr\fP directive.
  116. .IP \fB-gs\fR
  117. Do not generate sets for token expression lists; instead generate a
  118. \fB||\fP-separated sequence of \fBLA(1)==\fItoken_number\fR.  The
  119. default is to generate sets.
  120. .IP \fB-gt\fP
  121. Generate code for Abstract-Syntax Trees.
  122. .IP \fB-gx\fP
  123. Do not create the lexical analyzer files (dlg-related).  This option
  124. should be given when the user wishes to provide a customized lexical
  125. analyzer.  It may also be used in \fImake\fR scripts to cause only the
  126. parser to be rebuilt when a change not affecting the lexical structure
  127. is made to the input grammars.
  128. .IP "\fB-k \fIn\fR"
  129. Set k of LL(k) to \fIn\fR; i.e. set tokens of look-ahead (default==1).
  130. .IP "\fB-o\fP dir
  131. Directory where output files should go (default=".").  This is very
  132. nice for keeping the source directory clear of ANTLR and DLG spawn.
  133. .IP \fB-p\fP
  134. The complete grammar, collected from all input grammar files and
  135. stripped of all comments and embedded actions, is listed to
  136. \fBstdout\fP.  This is intended to aid in viewing the entire grammar
  137. as a whole and to eliminate the need to keep actions concisely stated
  138. so that the grammar is easier to read.  Hence, it is preferable to
  139. embed even complex actions directly in the grammar, rather than to
  140. call them as subroutines, since the subroutine call overhead will be
  141. saved.
  142. .IP \fB-pa\fP
  143. This option is the same as \fB-p\fP except that the output is
  144. annotated with the first sets determined from grammar analysis.
  145. .IP \fB-pr\fP
  146. Obsolete\ \(em used to turn on use of predicates in parsing decisions
  147. in release 1.06.  Now, in 1.10, the specification of a predicate
  148. implies that it should be used.  When a syntactic ambiguity is
  149. discovered, \fIantlr\fP searches for predicates that can be used to
  150. disambiguate the decision.  Predicates have dual roles as semantic
  151. validation and disambiguation predicates.
  152. .IP "\fB-prc on\fR
  153. Turn on the computation and hoisting of predicate context.
  154. .IP "\fB-prc off\fR
  155. Turn off the computation and hoisting of predicate context.  This
  156. option makes 1.10 behave like the 1.06 release with option \fB-pr\fR
  157. on.  Context computation is off by default.
  158. .IP "\fB-rl \fIn\fR
  159. Limit the maximum number of tree nodes used by grammar analysis to
  160. \fIn\fP.  Occasionally, \fIantlr\fP is unable to analyze a grammar
  161. submitted by the user.  This rare situation can only occur when the
  162. grammar is large and the amount of lookahead is greater than one.  A
  163. nonlinear analysis algorithm is used by PCCTS to handle the general
  164. case of LL(k) parsing.  The average complexity of analysis, however, is
  165. near linear due to some fancy footwork in the implementation which
  166. reduces the number of calls to the full LL(k) algorithm.  An error
  167. message will be displayed, if this limit is reached, which indicates
  168. the grammar construct being analyzed when \fIantlr\fP hit a
  169. non-linearity.  Use this option if \fIantlr\fP seems to go out to
  170. lunch and your disk start thrashing; try \fIn\fP=10000 to start.  Once
  171. the offending construct has been identified, try to remove the
  172. ambiguity that \fIantlr\fP was trying to overcome with large lookahead
  173. analysis.  The introduction of (...)? backtracking blocks eliminates
  174. some of these problems\ \(em \fIantlr\fP does not analyze alternatives
  175. that begin with (...)? (it simply backtracks, if necessary, at run
  176. time).
  177. .IP \fB-w1\fR
  178. Set low warning level.  Do not warn if semantic predicates and/or
  179. (...)? blocks are assumed to cover ambiguous alternatives.
  180. .IP \fB-w2\fR
  181. Ambiguous parsing decisions yield warnings even if semantic predicates
  182. or (...)? blocks are used.  Warn if predicate context computed and
  183. semantic predicates incompletely disambiguate alternative productions.
  184. .IP \fB-\fR
  185. Read grammar from standard input and generate \fBstdin.c\fP as the
  186. parser file.
  187. .SH "SPECIAL CONSIDERATIONS"
  188. .PP
  189. \fIAntlr\fP works...  we think.  There is no implicit guarantee of
  190. anything.  We reserve no \fBlegal\fP rights to the software known as
  191. the Purdue Compiler Construction Tool Set (PCCTS) \(em PCCTS is in the
  192. public domain.  An individual or company may do whatever they wish
  193. with source code distributed with PCCTS or the code generated by
  194. PCCTS, including the incorporation of PCCTS, or its output, into
  195. commercial software.  We encourage users to develop software with
  196. PCCTS.  However, we do ask that credit is given to us for developing
  197. PCCTS.  By "credit", we mean that if you incorporate our source code
  198. into one of your programs (commercial product, research project, or
  199. otherwise) that you acknowledge this fact somewhere in the
  200. documentation, research report, etc...  If you like PCCTS and have
  201. developed a nice tool with the output, please mention that you
  202. developed it using PCCTS.  As long as these guidelines are followed,
  203. we expect to continue enhancing this system and expect to make other
  204. tools available as they are completed.
  205. .SH FILES
  206. .IP *.c
  207. output C parser
  208. .IP *.C
  209. output C++ parser when C++ mode is used
  210. .IP \fBparser.dlg\fP
  211. output \fIdlg\fR lexical analyzer
  212. .IP \fBerr.c\fP
  213. token string array, error sets and error support routines
  214. .IP \fBremap.h\fP
  215. file that redefines all globally visible parser symbols.  The use of
  216. the #parser directive creates this file
  217. .IP \fBstdpccts.h\fP
  218. list of definitions needed by C files, not generated by PCCTS, that
  219. reference PCCTS objects.  This is not generated by default.
  220. .IP \fBtokens.h\fP
  221. output \fI#defines\fR for tokens used and function prototypes for
  222. functions generated for rules
  223. .SH "SEE ALSO"
  224. .LP
  225. dlg(1), pccts(1)
  226.